home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / old-compression / clAddAlgorithm.z / clAddAlgorithm
Encoding:
Text File  |  2002-10-03  |  14.8 KB  |  265 lines
  1.  
  2.  
  3.  
  4. ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))                                        ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      clAddAlgorithm, clSetUnique, clGetUnique, clFetchParam, clStoreParam,
  10.      clError - Add a video or audio compression algorithm to the Compression
  11.      Library
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ccccllll....hhhh>>>>
  15.  
  16.      iiiinnnntttt ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, iiiinnnntttt aaaallllggggTTTTyyyyppppeeee,,,, iiiinnnntttt mmmmaaaaxxxxHHHHeeeeaaaaddddeeeerrrrSSSSiiiizzzzeeee,,,,
  17.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ooooppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ccccoooommmmpppprrrreeeessssssss,,,,
  18.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr cccclllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr,,,,
  19.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ooooppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ddddeeeeccccoooommmmpppprrrreeeessssssss,,,,
  20.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr cccclllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr,,,,
  21.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr rrrreeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr qqqquuuueeeerrrryyyySSSScccchhhheeeemmmmeeee,,,,
  22.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr qqqquuuueeeerrrryyyyLLLLiiiicccceeeennnnsssseeee,,,,
  23.          FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr ggggeeeettttPPPPaaaarrrraaaammmmssss,,,, FFFFuuuunnnnccccttttiiiioooonnnnPPPPttttrrrr sssseeeettttPPPPaaaarrrraaaammmmssss,,,,
  24.          iiiinnnntttt ****sssscccchhhheeeemmmmeeee))))
  25.  
  26.      vvvvooooiiiidddd ****ccccllllSSSSeeeettttUUUUnnnniiiiqqqquuuueeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, vvvvooooiiiidddd ****uuuunnnniiiiqqqquuuueeee))))
  27.      vvvvooooiiiidddd ****ccccllllGGGGeeeettttUUUUnnnniiiiqqqquuuueeee((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee))))
  28.  
  29.      iiiinnnntttt  ccccllllFFFFeeeettttcccchhhhPPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD))))
  30.      vvvvooooiiiidddd ccccllllSSSSttttoooorrrreeeePPPPaaaarrrraaaammmm((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ppppaaaarrrraaaammmmIIIIDDDD,,,, iiiinnnntttt vvvvaaaalllluuuueeee))))
  31.  
  32.      vvvvooooiiiidddd ccccllllEEEErrrrrrrroooorrrr((((CCCCLLLLhhhhaaaannnnddddlllleeee hhhhaaaannnnddddlllleeee,,,, iiiinnnntttt ccccooooddddeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ffffoooorrrrmmmmaaaatttt,,,, ............))))
  33.  
  34.  
  35. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  36.      _n_a_m_e           A pointer to a string that contains the name of the
  37.                     algorithm.
  38.  
  39.      _a_l_g_T_y_p_e        The type of the algorithm (CCCCLLLL____AAAALLLLGGGG____VVVVIIIIDDDDEEEEOOOO or CCCCLLLL____AAAALLLLGGGG____AAAAUUUUDDDDIIIIOOOO).
  40.  
  41.      _m_a_x_H_e_a_d_e_r_S_i_z_e  The maximum size of the stream header for the specified
  42.                     algorithm.
  43.  
  44.      _o_p_e_n_C_o_m_p_r_e_s_s_o_r A pointer to the function that opens a compressor for the
  45.                     new algorithm.  The function must have the same arguments
  46.                     as ccccllllOOOOppppeeeennnnCCCCoooommmmpppprrrreeeessssssssoooorrrr.
  47.  
  48.      _c_o_m_p_r_e_s_s       A pointer to the function that compresses for the new
  49.                     algorithm.  The function must have the same arguments as
  50.                     ccccllllCCCCoooommmmpppprrrreeeessssssss.
  51.  
  52.      _c_l_o_s_e_C_o_m_p_r_e_s_s_o_r
  53.                     A pointer to the function that closes a compressor for the
  54.                     new algorithm.  The function must have the same arguments
  55.                     as ccccllllCCCClllloooosssseeeeCCCCoooommmmpppprrrreeeessssssssoooorrrr.
  56.  
  57.      _o_p_e_n_D_e_c_o_m_p_r_e_s_s_o_r
  58.                     A pointer to the function that opens a decompressor for
  59.                     the new algorithm.  The function must have the same
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))                                        ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.                     arguments as ccccllllOOOOppppeeeennnnDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr.
  75.  
  76.      _d_e_c_o_m_p_r_e_s_s     A pointer to the function that decompresses for the new
  77.                     algorithm.  The function must have the same arguments as
  78.                     ccccllllDDDDeeeeccccoooommmmpppprrrreeeessssssss.
  79.  
  80.      _c_l_o_s_e_D_e_c_o_m_p_r_e_s_s_o_r
  81.                     A pointer to the function that closes a decompressor for
  82.                     the new algorithm.  The function must have the same
  83.                     arguments as ccccllllCCCClllloooosssseeeeDDDDeeeeccccoooommmmpppprrrreeeessssssssoooorrrr.
  84.  
  85.      _r_e_a_d_H_e_a_d_e_r     A pointer to the function that reads the stream header for
  86.                     the new algorithm. The function must have the same
  87.                     arguments as ccccllllRRRReeeeaaaaddddHHHHeeeeaaaaddddeeeerrrr.
  88.  
  89.      _q_u_e_r_y_S_c_h_e_m_e    A pointer to the function that identifies the scheme from
  90.                     the stream header for the new algorithm. The function must
  91.                     have the same arguments as ccccllllQQQQuuuueeeerrrryyyySSSScccchhhheeeemmmmeeee.
  92.  
  93.      _q_u_e_r_y_L_i_c_e_n_s_e   A pointer to the function that checks for a NetLS license.
  94.                     The function must have the same arguments as
  95.                     ccccllllQQQQuuuueeeerrrryyyyLLLLiiiicccceeeennnnsssseeee.
  96.  
  97.      _g_e_t_P_a_r_a_m_s      A pointer to the function that gets
  98.                     compressor/decompressor parameters for the new algorithm.
  99.                     The function must have the same arguments as ccccllllGGGGeeeettttPPPPaaaarrrraaaammmmssss.
  100.  
  101.      _s_e_t_P_a_r_a_m_s      A pointer to the function that sets
  102.                     compressor/decompressor parameters for the new algorithm.
  103.                     The function must have the same arguments as ccccllllSSSSeeeettttPPPPaaaarrrraaaammmmssss.
  104.  
  105.      _s_c_h_e_m_e         A pointer to an int value to receive the compression
  106.                     scheme identifier.
  107.  
  108.      _h_a_n_d_l_e         A handle to a compressor/decompressor.
  109.  
  110.      _u_n_i_q_u_e         A pointer to the unique data structure used by the
  111.                     algorithm.
  112.  
  113.      _p_a_r_a_m_I_D        The parameter identifier.
  114.  
  115.      _v_a_l_u_e          The new value of the parameter.
  116.  
  117.      _c_o_d_e           The error code as specified in cl.h.  For errors not
  118.                     handled by the standard list, use
  119.                     CCCCLLLL____AAAADDDDDDDDEEEEDDDD____AAAALLLLGGGGOOOORRRRIIIITTTTHHHHMMMM____EEEERRRRRRRROOOORRRR.
  120.  
  121.      _f_o_r_m_a_t         A printf style format string.
  122.  
  123.       ...           Parameters to the printf style format string.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))                                        ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  141.      Users can add compression algorithms to the compression library by using
  142.      ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm.  When the user calls the compression library for this
  143.      added algorithm, some preprocessing is done and then the routines passed
  144.      to ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm are called.
  145.  
  146.      ccccllllSSSSeeeettttUUUUnnnniiiiqqqquuuueeee and ccccllllGGGGeeeettttUUUUnnnniiiiqqqquuuueeee allow the algorithm implementation to store
  147.      and retrieve algorithm-specific information with each instantiation of a
  148.      compressor or decompressor.  _o_p_e_n_C_o_m_p_r_e_s_s_o_r and _o_p_e_n_D_e_c_o_m_p_r_e_s_s_o_r should
  149.      set the unique pointer to initialize algorithm-specific storage.  Other
  150.      calls such as _c_o_m_p_r_e_s_s and _d_e_c_o_m_p_r_e_s_s should get the unique pointer if
  151.      they need to access the information from the handle.
  152.  
  153.      ccccllllFFFFeeeettttcccchhhhPPPPaaaarrrraaaammmm and ccccllllSSSSttttoooorrrreeeePPPPaaaarrrraaaammmm permit algorithm implementations to access
  154.      a handle's parameters directly, with minimal overhead.  Users of the
  155.      codec, however, should call the standard routines ccccllllGGGGeeeettttPPPPaaaarrrraaaammmm and
  156.      ccccllllSSSSeeeettttPPPPaaaarrrraaaammmm instead.
  157.  
  158.      ccccllllEEEErrrrrrrroooorrrr is used by new algorithm implementations to report errors.
  159.      Generally, the _f_o_r_m_a_t string starts with the cl routine name within which
  160.      the error occurred followed by a description of the error.
  161.  
  162.  
  163. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  164.      ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm returns SUCCESS, or a negative error code on failure.
  165.      ccccllllSSSSeeeettttUUUUnnnniiiiqqqquuuueeee returns the previous unique pointer, or NULL on failure.
  166.      ccccllllGGGGeeeettttUUUUnnnniiiiqqqquuuueeee returns the current unique pointer, or NULL on failure.
  167.      ccccllllFFFFeeeettttcccchhhhPPPPaaaarrrraaaammmm returns the parameter value.
  168.  
  169.  
  170.  
  171. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  172.           #include <dmedia/cl.h>
  173.            ...
  174.           int  newScheme;
  175.            ...
  176.           /* Add the new algorithm */
  177.           clAddAlgorithm("New Algorithm", CL_ALG_VIDEO,
  178.               NEW_ALGORITHM_MAX_HEADER_SIZE,
  179.               OpenNewCompressor, CompressNew, CloseNewCompressor,
  180.               OpenNewDecompressor, DecompressNew, CloseNewDecompressor,
  181.               ReadNewHeader, QueryNewScheme, QueryNewLicense,
  182.               GetNewParams, SetNewParams,
  183.               &newScheme);
  184.  
  185.           /* Compress a series of frames */
  186.           clOpenCompressor(newScheme, &handle);
  187.           for(i = 0; i < numberOfFrames; i++)
  188.           {
  189.               /* Get a frame from somewhere */
  190.               ...
  191.               clCompress(handle, 1, frameBuffer, &compressedBufferSize,
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))                                        ccccllllAAAAddddddddAAAAllllggggoooorrrriiiitttthhhhmmmm((((3333ddddmmmm))))
  203.  
  204.  
  205.  
  206.                          compressedBuffer);
  207.               /* Write the compressed data to somewhere else */
  208.               ...
  209.           }
  210.           clCloseCompressor(handle);
  211.  
  212.  
  213.  
  214. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  215.      CLintro(3dm), clOpenCompressor(3dm), clCompress(3dm),
  216.      clCloseCompressor(3dm), clOpenDecompressor(3dm), clDecompress(3dm),
  217.      clCloseDecompressor(3dm), clReadHeader(3dm), clQueryScheme(3dm),
  218.      clQueryLicense(3dm), clGetParams(3dm), clSetParams(3dm) clAddParam(3dm),
  219.      clSetDefault(3dm), clSetMin(3dm), clSetMax(3dm), clSetMinMax(3dm),
  220.      clSetRange(3dm)
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.